home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 576-600 / disk_587 / conlib / conlib.doc < prev    next >
Text File  |  1992-05-06  |  38KB  |  1,155 lines
  1.  
  2. ===============================================================================
  3. ===                                                                         ===
  4. ===                                                                         ===
  5. ===                   Documentation for Con.library V2.00                   ===
  6. ===                                                                         ===
  7. ===                                                                         ===
  8. ===============================================================================
  9.  
  10.  
  11.                    Con.library is developed by Bjørn Reese.
  12.  
  13.  
  14. --- Con.library ---------------------------------------------------------------
  15.  
  16. Con.library is a run time reentrant library, developed with the purpose to ease
  17. the living for application programmers. It contains functions to format and
  18. display texts, accept keys/messages, strings or numbers and to handle the cursor
  19. and screen controls, amongst other things. The library must be places in LIBS:
  20. to be used. This is version 2.00.
  21.  
  22.  
  23. --- Disclaimer ----------------------------------------------------------------
  24.  
  25. Con.library is tested to run as smoothly and bugfree as possible, but the
  26. author renounces any responsibility for faulty use of, or damages caused by,
  27. Con.library and all that goes with it.
  28.  
  29.  
  30. --- Distribution --------------------------------------------------------------
  31.  
  32. Con.library may be distributed freely with, and only with, the documentation,
  33. source and include files and if no charge is being made, except for a nominal
  34. media fee. Otherwise you need the written approval of the author.
  35.  
  36.  
  37. --- Commercial use ------------------------------------------------------------
  38.  
  39. Con.library may be used in commercial [ and non-commercial ] products without
  40. paying any royalties to the author. But I would be really happy to be
  41. mentioned. The documentation, source, includes and examples may be distributed
  42. along with the product without the written approval of the author.
  43.  
  44.  
  45. --- Public Domain -------------------------------------------------------------
  46.  
  47. The Con.library, the source, the includes and the examples is made Public
  48. Domain for two reasons:
  49.  
  50.         1) I am too busy to make any updates in the near future.
  51.         2) To support the wonderful idea of Public Domain and Shareware.
  52.  
  53. Please look in the "ConLib.readme" file to see exactly what Con.library should
  54. consist of.
  55.  
  56.  
  57.  
  58. ===============================================================================
  59.                                Why Con.library?
  60. ===============================================================================
  61.  
  62. Well, I have always wondered why Commodore had to make the Operating System so
  63. hard to get along with. As an assembler programmer I have always cursed the
  64. lack of an easy and comprehensive way to handle inputs and outputs to/from the
  65. screen [ like Basic's INPUT and PRINT ]. In Con.library I have combined the
  66. features of intuition windows and console.device, which gives the possibillity
  67. to use menues, gadgets etc. and also an easy control of cursor and text.
  68.  
  69.  
  70. ===============================================================================
  71.                                    Overview
  72. ===============================================================================
  73.  
  74. Some of the names of variable, constants, structures etc. may vary a little
  75. from language to language. Please refere to the includes for you language for
  76. the correct name.
  77.  
  78. --- Window --------------------------------------------------------------------
  79.  
  80. Before using the main functions of Con.library you must open a ConWindow, using
  81. the OpenCon function. Closing the ConWindow is done by CloseCon.
  82.  
  83. A "ConWindow" is just a normal Intuition Window connected with Console.device.
  84. So when you open the ConWindow it is done exactly the same way as OpenWindow()
  85. in Intuition.
  86.  
  87. --- Functions -----------------------------------------------------------------
  88.  
  89. The main functions of Con.library are DoFormat, Convert, Display, Accept and
  90. AcceptString.
  91.  
  92. - DoFormat converts a string and a list of arguments into a string in a
  93.   sprintf() or Exec.RawDoFmt() style.
  94.  
  95. - Convert converts a string into a numeric value.
  96.  
  97. - Display shows a text on the screen [ in a specific ConWindow ]. The text
  98.   is formatted before use, using DoFormat. For more information read the
  99.   description of Display.
  100.  
  101. - The Accept functions are designed to work just as you want it to, through
  102.   the use of numerous flags.
  103.  
  104.   o Accept is used to check if the user has pressed a defined key. You
  105.     can choose to wait until a key was pressed or just continue, echo the
  106.     pressed key or not, read both key presses and releases or just one of
  107.     them, and more. Accept can also be used to wait for messages [ like
  108.     MENUPICK or CLOSEWINDOW etc. ], except for RAWKEY and VANILLAKEY as
  109.     they are masked out by Accept.
  110.  
  111.   o AcceptString works in many way just like Basic's INPUT or a more like a
  112.     String Gadget. It's main purpose is to get a text string from the keyboard.
  113.     There are a couple of editing features like cursor movement, clear line,
  114.     clear to end of line, restore original buffer and so on.
  115.  
  116.   o You may accept a numerical value by using AcceptString and Convert.
  117.  
  118. Before using the Accept functions you must define which characters you will
  119. allow as ValidChars and as ExitChars [ see below ]. This is done with
  120. DefineChars. For a detailed information read the descriptions of the Accept
  121. functions and of DefineChars.
  122.  
  123. If a message is encountered in AcceptString one of the there different actions
  124. will be taken.
  125.  
  126.   o Ignore, if message is not defined in the Accept Structure [ acc_ExitFlags ]
  127.  
  128.   o Exit, if a Message Handler is not defined in the ConHandle Structure
  129.     [ cnh_MsgHandler = 0 ]
  130.  
  131.   o Jump to Message Handler, if it is defined [ cnh_MsgHandler containing a
  132.     pointer to a procedure ]. More information about this feature in the
  133.     description of SetMsgHandler.
  134.  
  135.  
  136. Besides from the functions mentioned above, there are a number of other
  137. functions, mainly to handle cursor and graphics control.
  138.  
  139. --- Characters ----------------------------------------------------------------
  140.  
  141. There are three types of characters:
  142.  
  143. - ValidChars are the characters which are accepted as input characters and
  144.   added to a possible input string.
  145.  
  146. - ExitChars are the characters which will terminate Accept/AcceptString
  147.   [ for instance <RETURN> or <ESC> ]. NB: Accept will also terminate on a
  148.   ValidChar, but with a different value in *Success*.
  149.  
  150. - EchoChars are the characters which may be echoed in the window. This only
  151.   works for the Accept functions [ it is not always smart to echo a <RETURN>
  152.   or likewise ]. EchoChars are treated independent from ValidChars and
  153.   ExitChars.
  154.  
  155. --- Types ---------------------------------------------------------------------
  156.  
  157. In this documentation I have used the types, which is specified in the
  158.  
  159.     - exec/types.i
  160.     - exec/types.h
  161.  
  162. includes from Commodore, to describe the functions and the structures. The
  163. descriptions in the "Short Description of Structures" section are only
  164. descriptive, and the actual include files may vary from language to language,
  165. so please look in the specific include(s) made for your language.
  166.  
  167.  
  168. ===============================================================================
  169.                             Quick list of functions
  170. ===============================================================================
  171.  
  172. OpenCon.........Opens a new ConWindow.
  173.  
  174. CloseCon........Closes a specific ConWindow.
  175.  
  176. DoFormat........Formats a text string [ like sprintf() ].
  177.  
  178. UserNotes.......Defines a specific user text [ to be used by DoFormat ]
  179.  
  180. DefineChars.....Defines Valid or Exit Chars used by Accept and AcceptString.
  181.  
  182. DisplayRaw......Prints an unformatted text in ConWindow.
  183.  
  184. Display.........Prints a formatted text in ConWindow.
  185.  
  186. Accept..........Gets an input [ key/message ] from console.
  187.  
  188. AcceptString....Gets a string from console.
  189.  
  190. SetMsgHandler...Set a new User Message Handler
  191.  
  192. GetInfo.........Get information about a specific ConWindow.
  193.  
  194. SetGfx..........Set Text Styles, Foreground and Background Colors.
  195.  
  196. GotoXY..........Places Cursor at a specific position.
  197.  
  198. Cursor..........Turns Cursor On or Off.
  199.  
  200. Scroll..........Scrolls the text in the ConWindow a specific amount of lines.
  201.  
  202. Convert.........Converts an ASCII string into a number [ DEC/HEX/OCT/BIN ]
  203.  
  204.  
  205. ===============================================================================
  206.                            Description of functions
  207. ===============================================================================
  208.  
  209. Following is an in-depth description of the functions in Con.library. It
  210. consists of four/five parts:
  211.  
  212. SYNTAX - a formal description of the function and its arguments. It is
  213.         represented in the following fashion:
  214.  
  215.                 Result = Function (Arguments)
  216.                   D0                 An/Dn
  217.  
  218.                 TYPE    Arguments
  219.  
  220.         If the function does not return a result it will be omitted from the
  221.         syntax description. The An/Dn are only of interrest to assembler
  222.         programmers as they state the registers used for a specific argument.
  223.         TYPE defines the type of the subsequent argument.
  224.  
  225. ARGUMENTS - a short description of the arguments used by the function.
  226.  
  227. RESULT - a short description of the result of the function.
  228.  
  229. DESCRIPTION - a verbal description of the function and what it does.
  230.  
  231. EXAMPLES - some examples of the usage.
  232.  
  233.  
  234. --- OpenCon -------------------------------------------------------------------
  235.  
  236. SYNTAX
  237. ~~~~~~
  238.         ConHandle = OpenCon (ConWindow,CursorMode)
  239.            D0                    A0        D0
  240.  
  241.         APTR    ConWindow
  242.         UWORD   CursorMode
  243.         APTR    ConHandle
  244.  
  245.  
  246. ARGUMENTS
  247. ~~~~~~~~~
  248. ConWindow
  249.         A pointer to a normal Intuition NewWindow Structure, which is also
  250.         used by OpenWindow() in Intuition.
  251. CursorMode
  252.         The cursor settings [ see Cursor ].
  253.  
  254.  
  255. RESULT
  256. ~~~~~~
  257. ConHandle
  258.         A pointer to a specific ConWindow Structure as defined in the includes.
  259.  
  260.  
  261. DESCRIPTION
  262. ~~~~~~~~~~~
  263. - OpenCon opens a ConWindow, which is a normal Intuition Window connected
  264. with Console.device. Use this function instead of OpenWindow() in Intuition.
  265.  
  266.  
  267. --- CloseCon ------------------------------------------------------------------
  268.  
  269. SYNTAX
  270. ~~~~~~
  271.         CloseCon (ConHandle)
  272.                      A0
  273.  
  274.         APTR    ConHandle
  275.  
  276.  
  277. ARGUMENTS
  278. ~~~~~~~~~
  279. ConHandle
  280.         [ See OpenCon ]
  281.  
  282.  
  283. DESCRIPTION
  284. ~~~~~~~~~~~
  285. - CloseCon closes the ConWindow which is specified by *ConHandle*.
  286.  
  287.  
  288. --- DoFormat ------------------------------------------------------------------
  289.  
  290. SYNTAX
  291. ~~~~~~
  292.         TextBuffer = DoFormat (ConHandle,String,FormatArgs,TextBuffer,BufferSize)
  293.             D0                    A0       A1       A2         A3         D0
  294.  
  295.         APTR    ConHandle
  296.         APTR    String
  297.         APTR    FormatArgs
  298.         APTR    TextBuffer
  299.         ULONG   BufferSize
  300.  
  301.  
  302. ARGUMENTS
  303. ~~~~~~~~~
  304. ConHandle
  305.         [ See OpenCon ]
  306. String
  307.         A pointer to the unformatted String [ NULL-terminated ].
  308. FormatArgs
  309.         A pointer to the arguments for formatting the string.
  310. TextBuffer
  311.         A pointer to where the result must be delivered.
  312. BufferSize
  313.         The maximum size of the formatted string.
  314.  
  315. RESULT
  316. ~~~~~~
  317. TextBuffer
  318.         A pointer to the formatted string.
  319.  
  320.  
  321. DESCRIPTION
  322. ~~~~~~~~~~~
  323.  
  324. - DoFormat works like the RawDoFmt() function in Exec.library or like the
  325. formatting part of sprintf() in C, but it has been improved over both. It
  326. formats a string, using an unformatted string and some formatting arguments.
  327. The unformatted string can contain two different types of formatting
  328. characters:
  329.  
  330.         - The Control Codes [ Represented by the "\" charackter (BackSlash) ]
  331.         - The Merging Codes [ -           -  -   "%" -          (Percent) ]
  332.  
  333. The Control Codes determines the appearance of the string. The following
  334. Control Codes are the same as those in sprintf():
  335.  
  336.         \b      = BackSpace             [ ASCII  8 ]
  337.         \t      = Tabulator             [ ASCII  9 ]
  338.         \n      = LineFeed              [ ASCII 10 ]
  339.         \v      = Vertical Tabulator    [ ASCII 11 ]
  340.         \f      = FormFeed              [ ASCII 12 ]
  341.         \r      = Carriage Return       [ ASCII 13 ]
  342.         \\      = The Character "\" itself
  343.  
  344. The following Control Codes are unique for Con.library:
  345.  
  346.         \[      = Escape                [ ASCII    27 ]
  347.         \{      = CSI                   [ ASCII   155 ]
  348.         \xxx    = Binary Value xxx      [ ASCII 0-255 ]
  349.         \*      = Binary Value (16 bits) from *FormatArgs*
  350.         \#x     = User Notes x          [ 1-8 ]
  351.         \@      = Plain Style
  352.         \B      = Bold Style
  353.         \I      = Italic Style
  354.         \U      = Underlined Style
  355.         \Cx     = Foreground Color      [ 0-9 ]
  356.         \Zx     = Background Color      [ 0-9 ]
  357.  
  358. \C and \Z does no error checking (as there can be more than 4 colors to choose
  359. from if WorkBench has been set to fx. 8 colors). Be sure that the values are
  360. correct as the are passed unchanged to "console.device". Only one digit is
  361. allowed!
  362.  
  363.  
  364. The Merging Codes is represented by the "%" character followed by a character
  365. which determines what the argument shall be treated as. This character may be
  366. one of the following:
  367.  
  368.         s       = String
  369.         c       = Character
  370.         d       = Signed Decimal Number
  371.         u       = Unsigned Decimal Number
  372.         x       = Hexadecimal Number
  373.         o       = Octal Number
  374.         b       = Binary Number
  375.         %       = The Character "%" itself
  376.  
  377. Please note that the argument for a string [ %s ] must be a pointer to a NULL-
  378. terminated string.
  379.  
  380. In the Merging Codes [ between the "%" and the character ] we may add some
  381. attributes, so that the Merging Codes can be represented by the following
  382. general syntax [ any of the attributes may be omitted ]:
  383.  
  384.         -0xxx.yyyl
  385.  
  386. ,where  -    Left Justifies the output [ otherwise Right Justified ]
  387.         0    For Numbers: Output leading zeroes instead of spaces
  388.              For Chars: Output leading user defined char [ default '.' ] ¹
  389.         xxx  Minimal field width
  390.         .yyy Maximal field width
  391.         l    Specify a 32 bits [ long ] argument [ otherwise 16 bits ] ²
  392.  
  393. ¹) Please note that the leading zeroes and spaces can be changed in the
  394.    ConHandle structure, BUT in the Merging Codes it is still represented by
  395.    a "0" character.
  396. ²) This does not apply for %s and %c. The %ls and %lc will cause an error.
  397.  
  398.  
  399. *FormatArgs* must be a succesive list of arguments. When a Merging Code is
  400. recognised in the text, the next value will be fetched from *FormatArgs*. The
  401. "\*" Control Code also fetches the next value from *FormatArgs*.
  402.  
  403. *TextBuffer* must be a pointer to an idle buffer in which the result is
  404. returned. Please note that the size of the *TextBuffer* must be bigger than
  405. the size of the *String* [ as the formatted string almost always is bigger than
  406. the unformatted string ] if *BufferSize* is not specified (ie. set to
  407. IGNOREVALUE).
  408.  
  409. The argument *TextBuffer* and the result *TextBuffer* is the same, but for
  410. future compatibillity please use the result *TextBuffer* [ ie. D0 ]
  411.  
  412. If an error is detected in the syntax of either Control Codes or Merging Codes,
  413. the interpretation of the specific code is terminated and is being outputted as
  414. a normal text.
  415.  
  416.  
  417. EXAMPLES
  418. ~~~~~~~~
  419. Control Codes:
  420.  
  421.   In the following examples we assume that User Note #3 is set to "Aliens".
  422.  
  423.         Unformatted string:             Formatted string:
  424.       ----------------------------------------------------------
  425.          "Hello World\n"                 "Hello World",10
  426.          "Ascii \65\\"                   "Ascii A\"
  427.          "\{1;1H"                        155,"1;1H"
  428.          "\fListen \#3\n"                12,"Listen Aliens",10
  429.  
  430.  
  431. Merging Codes:
  432.  
  433.         %8d     = A Decimal Number of minumum 8 Characters
  434.         %-8d    = As %8d but Left Justified
  435.         %08d    = As %8d but with Leading Zeros
  436.         %.40s   = A String of maximun 40 Characters
  437.  
  438.  
  439. --- UserNotes -----------------------------------------------------------------
  440.  
  441. SYNTAX
  442. ~~~~~~
  443.         UserNotes (ConHandle,UserText,NoteNumber)
  444.                       A0        A1        D0
  445.  
  446.         APTR    ConHandle
  447.         APTR    UserText
  448.         UWORD   NoteNumber
  449.  
  450.  
  451. ARGUMENTS
  452. ~~~~~~~~~
  453. ConHandle
  454.         [ See OpenCon ]
  455. UserText
  456.         A pointer to a NULL-terminating text
  457. NoteNumber
  458.         A number between 1 and 8 [ both included ]
  459.  
  460.  
  461. DESCRIPTION
  462. ~~~~~~~~~~~
  463. - UserNotes defines a specific user text [ used by \#x - see DoFormat ].
  464.  
  465.  
  466. --- DefineChars ---------------------------------------------------------------
  467.  
  468. SYNTAX
  469. ~~~~~~
  470.         DefineChars (Mode,BitTable,ArrayOfChars)
  471.                       D0     A1         A2
  472.  
  473.         ULONG   Mode
  474.         APTR    BitTable
  475.         APTR    ArrayOfChars
  476.  
  477.  
  478. ARGUMENTS
  479. ~~~~~~~~~
  480. Mode
  481.         A value telling how DefineChars should operate
  482. BitTable
  483.         A pointer to a BitTable
  484. ArrayOfChars
  485.         A pointer to a NULL-terminating string of ASCII characters
  486.  
  487.  
  488. DESCRIPTION
  489. ~~~~~~~~~~~
  490. - DefineChars creates a table of allowed characters for Accept and
  491. AcceptString. *Mode* indicates how you want to use DefineChars:
  492.  
  493.         DEFMODE_ALL     = Choose all keys
  494.         DEFMODE_NEW     = Start a new table
  495.         DEFMODE_ADD     = Add to table
  496.         DEFMODE_REM     = Remove from table
  497.         DEFMODE_GET     = Get a pre-defined table
  498.  
  499. The pre-defined tables are currently:
  500.  
  501.         DEFALL          = All possible values
  502.         DEFNONE         = No values at all
  503.         DEFALFANUM      = Alfanumeric values
  504.         DEFALFA         = Alfabetic values
  505.         DEFNUMERIC      = Numeric values
  506.         DEFDECIMAL      = Decimal values
  507.         DEFHEX          = Hexadecimal values
  508.         DEFOCTAL        = Octal values
  509.         DEFBINARY       = Binary values
  510.         DEFFLOAT        = Floating Point values
  511.  
  512. The Valid and Exit Tables are contained in the AcceptStructure. *ArrayOfChars*
  513. points to a NULL-terminating array of ASCII characters. If you want to use any
  514. special keys [ like the F-keys ] when use the AKEY_ which is specified in the
  515. includes.
  516.  
  517.  
  518. EXAMPLES
  519. ~~~~~~~~
  520. Define a new *BitTable*:
  521.  
  522.         Mode = DEFMODE_NEW
  523.  
  524. Define *BitTable* as all numeric values:
  525.  
  526.         Mode = DEFMODE_GET+DEFNUMERIC
  527.  
  528.  
  529. --- DisplayRaw ----------------------------------------------------------------
  530.  
  531. SYNTAX
  532. ~~~~~~
  533.         DisplayRaw (ConHandle,String,MaxLength)
  534.                        A0       A1       D0
  535.  
  536.         APTR    ConHandle
  537.         APTR    String
  538.         ULONG    MaxLength
  539.  
  540.  
  541. ARGUMENTS
  542. ~~~~~~~~~
  543. ConHandle
  544.         [ See OpenCon ]
  545. String
  546.         A pointer to a NULL-terminated text
  547. MaxLength
  548.         A max. length of the text
  549.  
  550.  
  551. DESCRIPTION:
  552.  
  553. - DisplayRaw prints an unformatted [ raw ] text on the ConWindow pointed
  554. to by *ConHandle*. This function is provided as a stripped and hence faster
  555. method to get a text on screen. If *MaxLength* is set to IGNOREVALUE then the
  556. text will terminate at NULL (not before).
  557.  
  558.  
  559. --- Display -------------------------------------------------------------------
  560.  
  561. SYNTAX
  562. ~~~~~~
  563.         Display (ConHandle,String,FormatArgs,MaxLength)
  564.                     A0       A1       A2         D0
  565.  
  566.         APTR    ConHandle
  567.         APTR    String
  568.         APTR    FormatArgs
  569.         ULONG   MaxLength
  570.  
  571.  
  572. ARGUMENTS
  573. ~~~~~~~~~
  574. ConHandle
  575.         [ See OpenCon ]
  576. String
  577.         A pointer to a NULL-terminated text
  578. FormatArgs
  579.         A pointer to the arguments for formatting the string.
  580. MaxLength
  581.         A max. length of the text
  582.  
  583.  
  584. DESCRIPTION
  585. ~~~~~~~~~~~
  586. - Display prints a formatted text [ see DoFormat ] on the ConWindow pointed
  587. to by *ConHandle*. Display calculates the length of the string and adds the
  588. value in cnh_ExLength [ default 256 ] to it. The value of cnh_ExLength can be
  589. changed at any given time, and if your format arguments requires more space,
  590. you must do so. No checking is performed.
  591.  
  592.  
  593. --- Accept --------------------------------------------------------------------
  594.  
  595. SYNTAX
  596. ~~~~~~
  597.         Success = Accept (ConHandle,AcceptStructure,Flags)
  598.           D0                 A0           A1          D0
  599.  
  600.         APTR    ConHandle
  601.         APTR    AcceptStructure
  602.         ULONG   Flags
  603.         LONG    Success
  604.  
  605.  
  606. ARGUMENTS
  607. ~~~~~~~~~
  608. ConHandle
  609.         [ See OpenCon ]
  610. AcceptStructure
  611.         A pointer to the normal AcceptStructure as defined in the includes.
  612. Flags
  613.         Determines how Accept shall execute
  614.  
  615.  
  616. RESULT
  617. ~~~~~~
  618. Success
  619.         Everything OK, an Error, an ExitFlag, an ExitChar or an user defined
  620.         value
  621.  
  622.  
  623. DESCRIPTION
  624. ~~~~~~~~~~~
  625. - Accept basically gets a key from the console, though it may function in
  626. other ways as well. *Flags* [ ACCF_ ] determines the way Accept works.
  627. *Success* tells how successful Accept was.
  628.  
  629.         Success = -1    => Error [ NULL in acc_Char ]
  630.         Success =  0    => OK [ Character in acc_Char ]
  631.         Success =  1    => ExitFlag [ Message information in AcceptStructure ]
  632.         Success =  2    => ExitChar [ Character in acc_Char ]
  633.  
  634. *Success* may also be an user defined value. More on this in the description of
  635. SetMsgHandler.
  636.  
  637. These are the flags for Accept:
  638.  
  639.         o ACCF_ERASE:
  640.                 Clear the Message Stack before reading. Caution! this also
  641.                 ignores messages like CLOSEWINDOW.
  642.         o ACCF_RAWKEY:
  643.                 Return RawKeys, otherwise return VanillaKeys.
  644.         o ACCF_DUALKEY:
  645.                 Report both key presses and releases, otherwise only one of
  646.                 them [ which will be dependent on ACCF_UPKEY ].
  647.         o ACCF_UPKEY:
  648.                 Report only when a key is released, otherwise only when a key
  649.                 is pressed. If ACCF_DUALKEY is selected, this flag will be
  650.                 ignored.
  651.         o ACCF_ECHO:
  652.                 Echo the key on the ConWindow, otherwise nothing appears. If
  653.                 ACCF_RAWKEY is selected, this flag will be ignored. Which keys
  654.                 will be echoed is determined by cnh_EchoTable in the ConHandle,
  655.                 which default is DEFALFANUM.
  656.         o ACCF_WAIT:
  657.                 Waits for reaction from the keyboard, otherwise do not wait. If
  658.                 a keypress [ or keyrelease dependent on ACCF_UPKEY ] was
  659.                 reported or found in the keyboard buffer, Accept will return
  660.                 with a OK, otherwise it will return with an Error.
  661.  
  662.  
  663. Accept may be terminated by an ExitFlag [ specified by acc_ExitFlags in the
  664. AcceptStructure ]. These ExitFlags are equvalent to the IDCMP flags from
  665. Intuition. This allows you to terminate Accept if fx. CLOSEWINDOW was chosen,
  666. or indeed use Accept to specifically wait for a message like CLOSEWINDOW.
  667.  
  668. When calling Accept you can amongst others specify its starting position on
  669. the screen and its styles and colors by setting the proper values in the
  670. AcceptStructure.
  671.  
  672. Also read the "Short Description of Structures" for further informations.
  673.  
  674.  
  675. --- AcceptString --------------------------------------------------------------
  676.  
  677. SYNTAX
  678. ~~~~~~
  679.         Success = AcceptString (ConHandle,AcceptStructure,Flags)
  680.           D0                       A0           A1          D0
  681.  
  682.         APTR    ConHandle
  683.         APTR    AcceptStructure
  684.         ULONG   Flags
  685.         LONG    Success
  686.  
  687.  
  688. ARGUMENTS
  689. ~~~~~~~~~
  690. ConHandle
  691.         [ See OpenCon ]
  692. AcceptStructure
  693.         A pointer to an extended AcceptStructure as defined in the includes
  694. Flags
  695.         Determines how AcceptString shall execute
  696.  
  697.  
  698. RESULT
  699. ~~~~~~
  700. Success
  701.         Everything OK, an Error, an ExitFlag or an user defined value
  702.  
  703.  
  704. DESCRIPTION
  705. ~~~~~~~~~~~
  706.  
  707. - AcceptString get a string. *Flags* determines the way AcceptString works.
  708. accs_MaxLength in *AcceptStructure* contains the maximum length of the string.
  709. It is very important to note that *AcceptStructure* must point to an extended
  710. Accept Structure, which contains further information needed for accepting a
  711. string [ the accs_ fields ].
  712.  
  713. When editing you can optionally use following keyboard combinations:
  714.  
  715.         <AMIGA x>       = Delete input text.
  716.         <AMIGA q>       = Restore original input text.
  717.         <AMIGA y>       = Delete input text from cursor until end of field.
  718.         <AMIGA a>       = Toggle between insert and overwrite.
  719.  
  720.         <BACKSPACE>     = Delete previous character
  721.         <DELETE>        = Delete current character
  722.         <CURSOR LEFT>   = Moves cursor one position left
  723.         <CURSOR RIGHT>  = -     -      -   -        right
  724.         <SHIFT CURSOR LEFT> = Moves cursor to end of field
  725.         <SHIFT CURSOR RIGHT>= Moves cursor to start of field
  726.  
  727.  
  728. If *InputBuffer* exceeds a line [ ie.  acc_XStart + acc_Length > cin_XSize ] it
  729. will be cut in length to fit the line, because an input field which continues
  730. onto a new line looks messy and is regarded as an error.
  731.  
  732. *Success* [ D0.L ] tells how successful AcceptString was.
  733.  
  734.         Success = -1    => Error
  735.         Success =  0    => OK [ String in accs_InputBuffer,
  736.                               and the length in accs_Length ]
  737.         Success =  1    => ExitFlag [ Message information in AcceptStructure ]
  738.  
  739. *Success* may also be an user defined value. More on this in the description of
  740. SetMsgHandler.
  741.  
  742.  
  743. These are the specific AcceptString flags:
  744.  
  745.         o ACCF_ERASE:
  746.                 Clear the Message Stack before reading. Caution! this also
  747.                 ignores messages like CLOSEWINDOW.
  748.         o ACCF_JUSTIFIED:
  749.                 Text will be rigth justified in the accept field, otherwise
  750.                 left justified.
  751.         o ACCF_CONTINUE:
  752.                 Continue editing the input, otherwise restart input. This is
  753.                 especially useful if Accept was terminated by an ExitFlag
  754.                 [ like MENUPICK or DISKREMOVED ]. Continuation is determined by
  755.                 acc_Position. This field is mostly internal, but can be used
  756.                 for setting a start position within the range of acc_Length.
  757.         o ACCF_OVERWRITE:
  758.                 Overwrite text, otherwise insert.
  759.         o ACCF_LASTEXIT:
  760.                 Exit the input if the input buffer is full [ accs_Length =
  761.                 accs_MaxLength ], otherwise allow continuing editing.
  762.         o ACCF_FULLSTOP:
  763.                 Stop inserting further characters if the input buffer is full.
  764.                 If ACCF_OVERWRITE is selected this flag will be ignored.
  765.         o ACCF_NOAMIGA:
  766.                 All <Amiga> combinations are disabled
  767.         o ACCF_NOSTDAMIGA:
  768.                 All non-standard <Amiga> combinations [ <y> and <a> ] are
  769.                 disabled.
  770.         o ACCF_NOSCROLL:
  771.                 Disable scrolling within input field. If accs_MaxLength bigger
  772.                 than accs_FieldLen it is cut in size.
  773.  
  774. For handling other messages sent duing an AcceptString you have two choices.
  775. Firstly you can let AcceptString terminate, handle the message and call
  776. AcceptString again with the ACCF_CONTINUE flag set. Secondly you can use the
  777. SetMsgHandler function for handling the message. This metode does not
  778. terminate AcceptString. For more information please read the description of
  779. SetMsgHandler.
  780.  
  781. Also read the "Short Description of Structures" for further informations.
  782.  
  783.  
  784. --- SetMsgHandler -------------------------------------------------------------
  785.  
  786. SYNTAX
  787. ~~~~~~
  788.         OldMsgHandler = SetMsgHandler(ConHandle,NewMsgHandler)
  789.              D0                          A0          A1
  790.  
  791.         APTR    ConHandle
  792.         APTR    NewMsgHandler
  793.         APTR    OldMsgHandler
  794.  
  795.  
  796. ARGUMENTS
  797. ~~~~~~~~~
  798. ConHandle
  799.         [ See OpenCon ]
  800. NewHandler
  801.         A pointer to your routine which handle messages
  802.  
  803.  
  804. RESULT
  805. ~~~~~~
  806. OldHandler
  807.         A pointer to the previous handler
  808.  
  809.  
  810. DESCRIPTION
  811. ~~~~~~~~~~~
  812. - It is possible to set your own Message Handler. This is activated if an
  813. Intuition Message occurs while performing Accept or AcceptString, but only if
  814. the flag is define in ExitFlags [ all others are ignored ].
  815.  
  816. Your handler should consist of what it normally does, for instance a Menu or
  817. Gadget Handler. A pointer to the message is delivered in both D0 and A0 to your
  818. handler. To get back to Accept/AcceptString simply return using RTS. If you want
  819. the Accept/AcceptString to continue set D0 to NULL. Any other value in D0 will
  820. terminate with the original value in D0 to let you determine what went wrong.
  821.  
  822. Please do not terminate your program immediately if you detect, say CLOSEWINDOW,
  823. because there is a lot of heap on the stack, which will only cause your program
  824. to crash if you try to exit it. The correct way to exit, is to set D0 to a
  825. certain value [ other than NULL and preferably other than -1 which means Error
  826. and 1 which means ExitFlag ] and return to Accept/AcceptString, and then catch
  827. the special error after the call of Accept/AcceptString.
  828.  
  829. To remove a handler simply set *NewMsgHandler* = NULL and call this function.
  830.  
  831.  
  832. --- GetInfo -------------------------------------------------------------------
  833.  
  834. SYNTAX
  835. ~~~~~~
  836.         ConInfo = GetInfo (ConHandle,ConInfo)
  837.           D0                  A0        A1
  838.  
  839.         APTR    ConHandle
  840.         APTR    ConInfo
  841.  
  842.  
  843. ARGUMENTS
  844. ~~~~~~~~~
  845. ConHandle
  846.         [ See OpenCon ]
  847. ConInfo
  848.         A pointer to a ConInfo structure
  849.  
  850.  
  851. RESULT
  852. ~~~~~~
  853. ConInfo - A pointer to an initialized ConInfo structure
  854.  
  855.  
  856. DESCRIPTION
  857. ~~~~~~~~~~~
  858. - GetInfo gets the current cursor and window settings as specified in the
  859. *ConInfo* structure.
  860.  
  861.  
  862. --- SetGfx --------------------------------------------------------------------
  863.  
  864. SYNTAX
  865. ~~~~~~
  866.         SetGfx (ConHandle,Styles,FgCol,BgCol)
  867.                    A0       D0     D1    D2
  868.  
  869.         APTR    ConHandle
  870.         UWORD   Styles
  871.         UWORD   FgCol
  872.         UWORD   BgCol
  873.  
  874.  
  875. ARGUMENTS
  876. ~~~~~~~~~
  877. ConHandle
  878.         [ See OpenCon ]
  879. Styles
  880.         Text Styling
  881. FgCol
  882.         Foreground Color
  883. BgCol
  884.         Background Color
  885.  
  886.  
  887. DESCRIPTION
  888. ~~~~~~~~~~~
  889. - SetGfx sets the text styles, foreground and background colors. The text
  890. *Styles* are defined in the includes. Currently the following flags are
  891. supported:
  892.  
  893.         SGFF_PLAIN
  894.         SGFF_BOLD
  895.         SGFF_ITALIC
  896.         SGFF_UNDERLINE
  897.  
  898. The colors must be specified as 30 - 3x and 40 - 4x, meaning 30 will set
  899. foreground to color 0 and 41 will set background to color 1.
  900.  
  901.  
  902. --- GotoXY --------------------------------------------------------------------
  903.  
  904. SYNTAX
  905. ~~~~~~
  906.         GotoXY (ConHandle, X, Y)
  907.                    A0     D0 D1
  908.  
  909.         APTR    ConHandle
  910.         UWORD   X
  911.         UWORD   Y
  912.  
  913.  
  914. ARGUMENTS
  915. ~~~~~~~~~
  916. ConHandle
  917.         [ See OpenCon ]
  918. X
  919.         Coloumn
  920. Y
  921.         Row
  922.  
  923.  
  924. DESCRIPTION
  925. ~~~~~~~~~~~
  926. - GotoXY places the cursor at a given position specified by (X,Y). The Top-Left
  927. corner is (1,1).
  928.  
  929.  
  930. --- Cursor --------------------------------------------------------------------
  931.  
  932. SYNTAX
  933. ~~~~~~
  934.         Cursor (ConHandle,Mode)
  935.                    A0      D0
  936.  
  937.         APTR    ConHandle
  938.         UWORD   Mode
  939.  
  940.  
  941. ARGUMENTS
  942. ~~~~~~~~~
  943. ConHandle
  944.         [ See OpenCon ]
  945. Mode
  946.         Cursor settings [ currently ON/OFF ]
  947.  
  948.  
  949. DESCRIPTION
  950. ~~~~~~~~~~~
  951. - Cursor handles the looks of the cursor. Currently two modes are supported:
  952.  
  953.         CURSOROFF       - Turns the cursor off.
  954.         CURSORON        - Turns the cursor on.
  955.  
  956.  
  957. --- Scroll --------------------------------------------------------------------
  958.  
  959. SYNTAX
  960. ~~~~~~
  961.         Scroll (ConHandle,Step)
  962.                    A0      D0
  963.  
  964.         APTR    ConHandle
  965.         WORD    Step
  966.  
  967.  
  968. ARGUMENTS
  969. ~~~~~~~~~
  970. ConHandle
  971.         [ See OpenCon ]
  972. Step
  973.         Lines to scroll
  974.  
  975.  
  976. DESCRIPTION
  977. ~~~~~~~~~~~
  978. - Scroll scrolls the text in the window the number of lines determined by
  979. *Step*. If it is positive the text will scroll down, and if it is negative the
  980. text will scroll up [ ie. if you want to scroll the text 2 lines up, you must
  981. set *Step* = -2 ].
  982.  
  983.  
  984. --- Convert -------------------------------------------------------------------
  985.  
  986. SYNTAX
  987. ~~~~~~
  988.         Result = Convert (String,ResultBuffer,Flags,MaxLength)
  989.           D0                 A1       A2       D0       D1
  990.  
  991.         APTR    String
  992.         APTR    ResultBuffer
  993.         ULONG   Flags
  994.         UWORD   MaxLength
  995.         APTR    Result
  996.  
  997.  
  998. ARGUMENTS
  999. ~~~~~~~~~
  1000. String
  1001.         NULL-terminating ASCII string containing the number to be converted.
  1002. ResultBuffer
  1003.         A pointer to an empty 32 bits location.
  1004. Flags
  1005.         Tells what number system to convert to [ DEC/HEX/OCT/BIN ] and some
  1006.         other attributes.
  1007. MaxLength
  1008.         The maximum length of the number to be converted.
  1009.  
  1010.  
  1011. RESULT
  1012. ~~~~~~
  1013. Result
  1014.         A pointer to the converted number OR NULL if any error occured.
  1015.  
  1016.  
  1017. DESCRIPTION
  1018. ~~~~~~~~~~~
  1019. - Convert converts an ASCII string to a binary value. The 'ResultBuffer' must
  1020. point to a longword. Please note that only the convertion ASCII->OCT have not
  1021. been implemented so far.
  1022.  
  1023. The actual length of *String* is calculated and used, except if *MaxLength*
  1024. specifies a smaller value. You can set *MaxLength* to IGNOREVALUE to ignore it.
  1025.  
  1026.  
  1027.  
  1028. ===============================================================================
  1029.                         Short Description of Structures
  1030. ===============================================================================
  1031.  
  1032. --- AcceptStructure -----------------------------------------------------------
  1033.  
  1034. acc_XStart, acc_YStart, acc_Styles, acc_FgCol and acc_BgCol can be set to any
  1035. defined value to get an action. If any these field are set to IGNOREVALUE then
  1036. the according field will be ignored [ = remain unchanged ].
  1037.  
  1038. If any of the Accept functions terminates because of an ExitFlag, the relevant
  1039. values from the message can be found in the AcceptStructure.
  1040.  
  1041. If ACC_RAWKEY was chosen the result will NOT be in acc_Char but in acc_Code.
  1042.  
  1043.  
  1044. ===============================================================================
  1045.                                About the Source
  1046. ===============================================================================
  1047.  
  1048. The source is made for the exellent "AsmOne" assembler, but it should work with
  1049. "Devpac 2" - I think - if minor changes are made, like converting the square
  1050. brackets [] with the normal brackets ().
  1051.  
  1052. Originally the source was not intended to be released, but in the last minute I
  1053. changed my mind for reasons stated elsewhere in this documentation, therefore
  1054. the source is not very well documented (Sorry!).
  1055.  
  1056.  
  1057. ===============================================================================
  1058.                                      Ideas
  1059. ===============================================================================
  1060.  
  1061. In my brainstorming list there are still some unused ideas:
  1062.  
  1063.         o Implementation of Floats [ in DoFormat and Convert ]
  1064.  
  1065.         o A group seperator in DoFormat [ fx. "%1001.0111" instead of
  1066.           "%10010111" and "19.443.422" instead of "19443422" ]. This would
  1067.           give us -0xxx.yyy.zzzl as the general syntax for DoFormat, where
  1068.           .zzz is the width of the groups [ 4 in the first and 3 in the
  1069.           second example ].
  1070.  
  1071.  
  1072. ===============================================================================
  1073.                                     History
  1074. ===============================================================================
  1075.  
  1076. Version 1.00a:
  1077.  
  1078. - Lots of thinking, designing and programming.
  1079. - First unofficially released version [ alfa version ].
  1080.  
  1081.  
  1082. Version 1.00b:
  1083.  
  1084. - cnh_CursStatus renamed to cnh_CursorStatus.
  1085. - *Success* was not reported in Accept/AcceptString, but it is now.
  1086. - cnh_EchoTable determines which chars may be echoed and which may not.
  1087.  
  1088.  
  1089. Version 1.01:
  1090.  
  1091. - DoFormat totally rewritten. I was previously using RawDoFmt() in Exec, but
  1092.   it leaves a lot to be desired, so I wrote my own routines. As far as I can
  1093.   tell, DoFormat acts like RawDoFmt() but it adds a lot of features, and
  1094.   removed a minor bug in RawDoFmt().
  1095. - AcceptString added as a seperate function. Accept is now that previously
  1096.   known as AcceptKey.
  1097. - AcceptString rewritten. It now scrolls back and forth if the accept field
  1098.   is smaller than the actual maximum input size.
  1099. - AcceptStructure rewritten [ several times ].
  1100. - UserNotes added.
  1101. - Lots of alternate padding characters [ like Decimal point, Leading zeroes ].
  1102. - cnh_MsgHandler added.
  1103. - Documentation rewritten to fit the new features.
  1104.  
  1105.  
  1106. Version 1.02:
  1107.  
  1108. - ReplyMsg() added. OS2.0 seemed to bug with the omission of this.
  1109. - The important parts of the Intuition Message are copied to AcceptStructure.
  1110. - Some of the special keys [ like the F-keys ] was not working. They are now.
  1111. - Convert added.
  1112.  
  1113.  
  1114. Version 2.00:
  1115.  
  1116. - First public release.
  1117.  
  1118.  
  1119. ===============================================================================
  1120.                            KNOWN BUGS AND OMISSIONS
  1121. ===============================================================================
  1122.  
  1123. - Octal values [ CNV_OCTAL ] are not implemented in Convert [ Does anybody use
  1124.   them anyway? ]
  1125. - Attributes [ CNV_SIGNED and CNV_LEADSPACE ] are not implemented in Convert.
  1126. - Long Unsigned in DoFormat [ %lu ] bugs if value >= $80000000.
  1127.  
  1128.  
  1129. ===============================================================================
  1130.                                   Thank you's
  1131. ===============================================================================
  1132.  
  1133. I would like to express my gratitude to following:
  1134.  
  1135. Jesper B. Krogholt:
  1136.  
  1137.         o For his major support and suggestions during development.
  1138.  
  1139.         o For making the Modula-2 interface.
  1140.  
  1141. Michael Berg:
  1142.  
  1143.         o For making the C interface.
  1144.  
  1145.  
  1146. ===============================================================================
  1147.  
  1148. Any comments, suggestions, bugreports, gifts etc. can be directed to the author
  1149. on this address:
  1150.  
  1151.         Bjørn Reese
  1152.         Stammen 55, -2
  1153.         DK-5220 Odense SØ
  1154.         Denmark
  1155.